<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.15">
<title>Node.js Support</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />

<!-- ************* OpenGraph ************-->
<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">

<meta property="og:site_name" content="Eclipse N4JS"/>
<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
<meta property="og:url" content="https://numberfour.github.io/n4js"/>
<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
<meta property="og:image" content="../images/n4js.png">

<!-- ************* Favicon ************-->
<link rel="icon" href="../images/favicon.ico" />
<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />

<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>

<!-- ************* Prism.js Syntax Highlighter ******-->
<link href="../styles/prism.min.css" rel="stylesheet"/>
<script src="../scripts/prism.js"></script>

<!-- ************* Styles ************* -->

<link rel="stylesheet" type="text/css" href="../styles/n4js-adoc.css">

<!-- ****************** NavBar ****************** -->
<div id="menubar">
    <div class="banner">
        <a href="../index.html"><img id="logo" src="../images/n4js-logo.png" alt="Eclipse N4JS Language and IDE"></a>
    </div>
<ul>
  <li><a href="../downloads.html"></i>Download</a></li>
  <li><a href="../community.html"></i>Community</a></li>
  <li><a href="../userguides/index.html">Documentation</a></li>
</ul>
</div>
<button id="tocbutton">TOC</button>
</head>
<body class="book">
<div id="header">
</div>
<div id="content">
<h1 id="_node_js_support" class="sect0"><a class="link" href="#_node_js_support">Node.js Support</a></h1>
<div class="openblock partintro">
<div class="title">Node.js Support</div>
<div class="content">
N4JS and its IDE are optimized to develop large scale server applications with <a href="https://nodejs.org">Node.js</a>
Besides launching and testing code from the IDE using Node.js, additional support is provided for automatically downloading
<a href="https://www.npmjs.com/">npm</a> packages and exporting N4JS projects to npm. This allows for seamless integration
of N4JS projects with existing Node.js based environments.
</div>
</div>
<div class="sect1">
<h2 id="_installing_and_using_npm_packages"><a class="link" href="#_installing_and_using_npm_packages">Installing and using npm packages</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>N4JS helps Node.js developers to use third-party npm packages with support both on the language and tooling level. The
required packages can be downloaded and installed on-demand into the IDE via the library manager and this feature is also
supported in the headless tooling.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/quickfixnpminstall.png" alt="quickfixnpminstall">
</div>
</div>
<div class="sect2">
<h3 id="_dynamic_import"><a class="link" href="#_dynamic_import">Dynamic Import</a></h3>
<div class="paragraph">
<p>Third-party packages are supported in two different ways. If an npm package does not have any corresponding type definition
files defined yet, then the required module can be imported into an N4JS module dynamically. In order to support the import
of modules without any N4JS (<code>.n4js</code>) or N4JS type definition (<code>.n4jsd</code>) files, N4JS extends the ES2015
module import. This is done by declaring the imported module with &#8220;+&#8221; appended to the end of the named import.
This so called "dynamic module import" will be treated as a type of <code>any+</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">import * as mongodb+ from 'mongodb';

var client = mongodb.MongoClient;

client.connect("…", function (err, db: any+) {
    if (err) {
        console.log('Unable to connect to the mongoDB:', err);
    } else {
        …
        db.close();
        console.log('Connection closed at', url);
    }
});</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the example above, <code>mongodb</code> is dynamically imported. It is therefor possible to access arbitrary properties,
such as the "class" <code>MongoClient</code> in line 3. The type of these properties will become any+ as well, so that it is
possible to access properties from the class as well, as shown in line 5 and 10.</p>
</div>
</div>
<div class="sect2">
<h3 id="_automatic_download_of_type_definitions"><a class="link" href="#_automatic_download_of_type_definitions">Automatic Download of Type Definitions</a></h3>
<div class="paragraph">
<p>If type definitions are available at <a href="https://github.com/NumberFour/n4jsd">our N4JS type definition project</a> for a
particular npm package
these definitions will be included automatically when the npm package is being downloaded and installed. All npm packages with
type definitions seamlessly integrate into the N4JS system. This means that all third-party npm packages with the correct type
definitions behave just like any other N4JS module or project declared in the workspace. The language provides type safety while
the tooling provides content assist, navigation, search functionality and so on.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/nodejs.png" alt="nodejs">
</div>
</div>
<div class="paragraph">
<p>The IDE also supports a way to check for any type definition updates in an on-demand fashion. This means that you can initially
begin to use any third-party packages that don&#8217;t yet have type definition files. In such cases (as described above) the modules
from the npm packages have to be imported dynamically.
It&#8217;s then possible to perform a manual refresh from the IDE and the
application will check for any type definition updates. If the type definitions have been declared and been made available,
meanwhile, the application will download the definitions and warn the user at the location of the dynamic imports about the
availability of the type definition file. It&#8217;s then possible to switch to the type safe approach by removing the appended
<code>+</code> from the named module import.</p>
</div>
<div class="paragraph">
<p>At the moment, writing type definition files requires to manually set up a new project and configuring the manifest etc.
accordingly. We will improve supporting that to simplify users to write new and enrich existing type definitions and share
them with others via <a href="https://github.com/NumberFour/n4jsd">our N4JS type definition project</a> in future releases.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_exporting_n4js_projects_as_npm_packages"><a class="link" href="#_exporting_n4js_projects_as_npm_packages">Exporting N4JS projects as npm packages</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Besides supporting npm package download and usage, the IDE comes with an npm package export feature.
Any N4JS workspace project can then be transformed into a structure that complies to npm requirements and can be exported
into the local file system.
These exported structures can later be used to manually publish them as packages to npm.
The corresponding <code>package.json</code> file will be created based on the dependencies declared in the N4JS manifest file of
the exported N4JS project.
Although all direct and transitive dependencies will be included in the brand new <code>package.json</code> file, only the
desired N4JS projects will be transformed and exported.
The <code>package.json</code> content can be customized by creating a <code>package.json</code> template file in the root of
the N4JS project
With this template, additional attributes can be defined.
This feature is further explained in the <a href="../userguides/npm-export-guide.html.html#npm_export_guide">npm export guide</a>.</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
</div>
</div>
<div class="Grid social" style="color:#d5dfea">
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <h2>Quick Links</h2>
    <ul>
      <li><a href="../downloads.html">Download</a></li>
      <li><a href="../userguides/index.html">Documentation</a></li>
      <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
      <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
      <li><a href="http://n4js.blogspot.de/">Blog</a></li>
      <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
      <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
      <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
      <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
      <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
      <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
      <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
    </ul>
  </div>
  <div style="clear: both; height: 0; overflow: hidden;"></div>
</div>

<script>
  // Toggle the table of contents
  $( "button#tocbutton" ).click(function() {
    if ($("#tocbutton").css('right') == '25px') {
      $( "#tocbutton" ).animate({right: '215px'},"slow");
      $( "#toc.toc2" ).animate({right: '0'},"slow");
  }
    else {
      $( "#tocbutton" ).animate({right: '25px'},"slow");
      $( "#toc.toc2" ).animate({right: '-13rem'},"slow");
  }
  });
</script>

<script type="text/javascript">
  // Create a back to top button
  $('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
  var amountScrolled = 300;
  $(window).scroll(function() {
  if ( $(window).scrollTop() > amountScrolled ) {
  	$('a.back-to-top').fadeIn('slow');
  } else {
  	$('a.back-to-top').fadeOut('slow');
  }
  });
  $('a.back-to-top, a.simple-back-to-top').click(function() {
  $('html, body').animate({
  	scrollTop: 0
  }, 700);
  return false;
  });
</script>
</body>
</html>